<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <meta>
  <!-- Stylesheets -->
  <link href="../web.css" type="text/css" rel="stylesheet"></link>
  <link href="../pygmentize.css" type="text/css" rel="stylesheet"></link>
  <title>VLFeat - Documentation - C API</title>
  <link rel="stylesheet" type="text/css" href="../doxygen.css"></style>

  <!-- Scripts-->
  
 </meta>

 <!-- Body Start -->
 <body>
  <div id="header">
   <!-- Google CSE Search Box Begins -->
   <form action="http://www.vlfeat.org/search.html" method="get" id="cse-search-box" enctype="application/x-www-form-urlencoded">
    <div>
     <input type="hidden" name="cx" value="003215582122030917471:oq23albfeam"></input>
     <input type="hidden" name="cof" value="FORID:11"></input>
     <input type="hidden" name="ie" value="UTF-8"></input>
     <input type="text" name="q" size="31"></input>
     <input type="submit" name="sa" value="Search"></input>
    </div>
   </form>
   <script src="http://www.google.com/coop/cse/brand?form=cse-search-box&amp;lang=en" xml:space="preserve" type="text/javascript"></script>
   <!-- Google CSE Search Box Ends -->
   <h1><a shape="rect" href="../index.html" class="plain"><span id="vlfeat">VLFeat</span><span id="dotorg">.org</span></a></h1>
  </div>
  <div id="headbanner">
   Documentation - C API
  </div>
  <div id="pagebody">
   <div id="sidebar"> <!-- Navigation Start -->
    <ul>
<li><a href="../index.html">Home</a>
</li>
<li><a href="../download.html">Download</a>
</li>
<li><a href="../doc.html">Documentation</a>
<ul>
<li><a href="../mdoc/mdoc.html">Matlab API</a>
</li>
<li><a href="index.html" class='active' >C API</a>
</li>
<li><a href="../man/man.html">Man pages</a>
</li>
</ul></li>
<li><a href="../overview/tut.html">Tutorials</a>
</li>
<li><a href="../applications/apps.html">Applications</a>
</li>
</ul>

   </div> <!-- sidebar -->
   <div id="content">
    
    <link rel="stylesheet" type="text/css" href="../doxygen.css"></style>
    <div class="doxygen">
<div>
<!-- Generated by Doxygen 1.7.5.1 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<div class="title">VLFeat design concepts </div>  </div>
</div>
<div class="contents">
<div class="textblock"><p>VLFeat is designed to be portable and simple to integrate with high level languages such as MATLAB. This section illustrates and motivates the aspects of the design that are relevant to the users of the library.</p>
<h2><a class="anchor" id="design-resources"></a>
Memory and resource handling</h2>
<p>Some VLFeat functions return pointers to memory blocks or objects. Only <a class="el" href="generic_8h.html#a136474bd173eb04e98989c7a521d4ada" title="Call customizable malloc function.">vl_malloc</a>, <a class="el" href="generic_8h.html#a175a5268fe40a4e3c68e6fab63ed064b" title="Call customizable calloc function.">vl_calloc</a>, <a class="el" href="generic_8h.html#a6213d08692fb90f0a0eaa423644f25c2" title="Call customizable resize function.">vl_realloc</a>, or functions whose name contains either the keywords <code>new</code> or <code>copy</code>, transfer the ownership of the memory block or object to the caller. The caller must dispose explicitly of all the resources he owns (by calling <a class="el" href="generic_8h.html#ae070a0a4d3d367a1ba8308644c88ada3" title="Call customizable free function.">vl_free</a> for a memory block, or the appropriate destructor for an object).</p>
<p>The memory allocation functions can be customized by <a class="el" href="generic_8h.html#ac04fe278ac908fa6ed02bda099588cf0" title="Set memory allocation functions.">vl_set_alloc_func</a> (which sets the implementations of <a class="el" href="generic_8h.html#a136474bd173eb04e98989c7a521d4ada" title="Call customizable malloc function.">vl_malloc</a>, <a class="el" href="generic_8h.html#a6213d08692fb90f0a0eaa423644f25c2" title="Call customizable resize function.">vl_realloc</a>, <a class="el" href="generic_8h.html#a175a5268fe40a4e3c68e6fab63ed064b" title="Call customizable calloc function.">vl_calloc</a> and <a class="el" href="generic_8h.html#ae070a0a4d3d367a1ba8308644c88ada3" title="Call customizable free function.">vl_free</a>). Remapping the memory allocation functions can be done only if there are no currently allocated VLFeat memory blocks or objects. The memory allocation functions are common to all threads.</p>
<p>VLFeat uses three rules that simplify handling exceptions:</p>
<ul>
<li>The library allocates local memory only through the reprogrammable <a class="el" href="generic_8h.html#a136474bd173eb04e98989c7a521d4ada" title="Call customizable malloc function.">vl_malloc</a>, <a class="el" href="generic_8h.html#a175a5268fe40a4e3c68e6fab63ed064b" title="Call customizable calloc function.">vl_calloc</a>, and <a class="el" href="generic_8h.html#a6213d08692fb90f0a0eaa423644f25c2" title="Call customizable resize function.">vl_realloc</a> functions.</li>
</ul>
<ul>
<li>The only resource referenced by VLFeat objects is memory (for instance, it is illegal for an object to reference an open file). Other resources such as files or threads may be allocated within a VLFeat function call, but they are all released before the function ends, or their ownership is directly transferred to the caller.</li>
</ul>
<ul>
<li>The global library state is an exception. It cannot reference any local object created by the caller and uses the standard C memory allocation functions.</li>
</ul>
<p>In this way, the VLFeat local state can be reset at any time simply by disposing of all the memory allocated so far. The latter can be done easily by mapping the memory allocation functions to implementations that track the memory blocks allocated, and simply disposing of all such blocks. Since the global state does not reference any local object nor uses the remapped memory functions, it is unaffected by such an operation; conversely, since no VLFeat object references anything but memory, this guarantees that all allocated resources are properly disposed (no leaks). This is used extensively in the design of MATLAB MEX files (see <a class="el" href="design.html#design-matlab">MATLAB integration issues</a>).</p>
<h2><a class="anchor" id="design-objects"></a>
Objects</h2>
<p>Many VLFeat algorithms are availale in the form of &ldquo;objects&rdquo;. Notice that the C language, used by VLFeat, does not support objects explicitly. Here an object indicates an opaque data structure along with a number of functions (methods) operationg on it.</p>
<p>Object names are captilaised and start with the <code>Vl</code> prefix (for example <a class="el" href="structVlSiftFilt.html" title="SIFT filter.">VlSiftFilt</a>). Object methods are lowercase and start with the <code>vl_&lt;object_name&gt;_</code> suffix (e.g. <a class="el" href="sift_8h.html#adff66a155e30ed412bc8bbb97dfa2fae" title="Create a new SIFT filter.">vl_sift_new</a>). Object methods typraically include a constructor (e.g. <a class="el" href="sift_8h.html#adff66a155e30ed412bc8bbb97dfa2fae" title="Create a new SIFT filter.">vl_sift_new</a>), a destructor (<a class="el" href="sift_8h.html#ab242293326626641411e7d7f43a109b2" title="Delete SIFT filter.">vl_sift_delete</a>), some getter methods (<a class="el" href="sift_8h.html#a70186e579c8eff1bcabf408f46169cad" title="Get current octave index.">vl_sift_get_octave_index</a>), and some setter methods (<a class="el" href="sift_8h.html#a595579dd7952807c074c5311a6500121" title="Set the magnification factor.">vl_sift_set_magnif</a>).</p>
<h2><a class="anchor" id="design-threads"></a>
Multi-threading</h2>
<p>VLFeat can be used with multiple threads by treating appropriately different kinds of operations:</p>
<ul>
<li><b>Local operations (reentrancy).</b> Most VLFeat operations are reentrant, in the sense that they operate on local data. It is safe to execute such operations concurrently from multiple threads as long as each thread operates on an independent sets of objects or memory blocks. By contrast, operating on the same object or memory block from multiple threads requires proper synchronization by the user.</li>
</ul>
<ul>
<li><b>Task-specific operations.</b> A few operations are intrinsically non-reentrant but thread-specific. These include: retrieving the last error by <a class="el" href="generic_8h.html#ac1a9bdc5e32a00ca28599b8daf5e0d50" title="Get VLFeat last error code.">vl_get_last_error</a> and obtaining the thread-specific random number generator by <a class="el" href="generic_8h.html#ac0ce7fb575acd4f01cbb4a275ba84700" title="Get the random number generator for this thread.">vl_get_rand</a>. VLFeat makes such operations thread-safe by operating on task-specific data.</li>
</ul>
<ul>
<li><b>Global operations.</b> A small number of operations are non-reentrant <em>and</em> affect all threads simultaneously. These are restricted to changing certain global configuration parameters, such as the memory allocation functions by <a class="el" href="generic_8h.html#ac04fe278ac908fa6ed02bda099588cf0" title="Set memory allocation functions.">vl_set_alloc_func</a>. These operations are <em>not</em> thread safe and should be executed before multiple threads are started.</li>
</ul>
<p>Some VLFeat algorithms are randomised. Each thread has his own random number generator (an instance of <a class="el" href="structVlRand.html" title="Random numbber generator state.">VlRand</a>) accessed by <a class="el" href="generic_8h.html#ac0ce7fb575acd4f01cbb4a275ba84700" title="Get the random number generator for this thread.">vl_get_rand</a>. To make calculations reproducible the random number generator must be seeded appropriately in each thread. Notice also that using the same VLFeat object from multiple threads (with appropriate synchronization) will cause multiple random number generators to be intermixed.</p>
<h2><a class="anchor" id="design-portability"></a>
Portability features</h2>
<p>Platform dependent details are isolated in the <a class="el" href="host_8h.html">host.h</a> library module. These include:</p>
<ul>
<li>Atomic types (e.g. <a class="el" href="host_8h.html#a03fa435c713d3141c4a700f79f5b2600" title="Signed 32-bit integer.">vl_int32</a>).</li>
<li>Special syntaxes for the declaration of symbols exported by the library and inline functions (e.g. <a class="el" href="host_8h.html#a489d7622ef2e3937985fcb9f89a5cbe5" title="Declares a DLL exported symbol.">VL_EXPORT</a>).</li>
<li>Host-dependent conversion of data endianess (e.g. <a class="el" href="host_8h.html#a0eb83ae66c944bcd8517b577b557f872" title="Host &lt;-&gt; big endian transformation for 8-bytes value.">vl_swap_host_big_endianness_8()</a>).</li>
</ul>
<p>VLFeat uses processor specific features (e.g. Intel SSE) if those are available at run time.</p>
<h2><a class="anchor" id="design-matlab"></a>
MATLAB integration issues</h2>
<p>The VLFeat C library is designed to integrate seamlessly with MATLAB. Binary compatibility is simplified by the use of the C language (rather than C++). In addition, the library design follows certain restrictons that make it compatible with the MATLAB MEX interface.</p>
<p>The main issue in calling a library function from a MATLAB MEX function is that MATLAB can abort the execution of the MEX function at any point, either due to an error, or directly upon a user request (Ctrl-C) (empirically, however, a MEX function seems to be interruptible only during the invocation of certain functions of the MEX API such as <code>mexErrMsgTxt</code>).</p>
<p>When a MEX function is interrupted, resources (memory blocks or objects) whose ownership was transferred from VLFeat to the MEX function may be leaked. Notice that interrupting a MEX function would similarly leak any memory block allocated within the MEX function. To solve this issue, MATLAB provides his own memory manager (<code>mxMalloc</code>, <code>mxRealloc</code>, ...). When a MEX file is interrupted or ends, all memory blocks allocated by using one of such functions are released, preventing leakage.</p>
<p>In order to integrate VLFeat with this model in the most seamless way, VLFeat memory allocation functions (<a class="el" href="generic_8h.html#a136474bd173eb04e98989c7a521d4ada" title="Call customizable malloc function.">vl_malloc</a>, <a class="el" href="generic_8h.html#a6213d08692fb90f0a0eaa423644f25c2" title="Call customizable resize function.">vl_realloc</a>, <a class="el" href="generic_8h.html#a175a5268fe40a4e3c68e6fab63ed064b" title="Call customizable calloc function.">vl_calloc</a>) are mapped to the corresponding MEX memory allocation functions. Such functions automatically dispose of all the memory allocated by a MEX function when the function ends (even because of an exception). Because of the restrictions of the library design illustrated in <a class="el" href="design.html#design-resources">Memory and resource handling</a>, this operation is safe and correctly dispose of VLFeat local state. As a consequence, it is possible to call <code>mexErrMsgTxt</code> at any point in the MEX function without worring about leaking resources.</p>
<p>This however comes at the price of some limitations. Beyond the restrictions illustred in <a class="el" href="design.html#design-resources">Memory and resource handling</a>, here we note that no VLFeat local resoruce (memory blocks or objects) can persist across MEX file invocations. This implies that any result produced by a VLFeat MEX function must be converted back to a MATLAB object such as a vector or a structure. In particular, there is no direct way of creating an object within a MEX file, returning it to MATLAB, and passing it again to another MEX file.</p>
<h2><a class="anchor" id="main-metaprogramming"></a>
Preprocessor metaprogramming</h2>
<p>Part of VLFeat code uses a simple form of perprocessor metaprogramming. This technique is used, similarly to C++ templates, to instantiate multiple version of a given algorithm for different data types (e.g. <code>float</code> and <code>double</code>).</p>
<p>In most cases preprocessor metaprogramming is invisible to the library user, as it is used only internally. </p>
</div></div>
     <!-- Doc Here -->
    </div>
   
   </div>
   <div class="clear">&nbsp;</div>
  </div> <!-- pagebody -->
  <div id="footer">
   &copy; 2007-12 Andrea Vedaldi and Brian Fulkerson
  </div> <!-- footer -->

  <!-- Google Analytics Begins -->
  <script xml:space="preserve" type="text/javascript">
   //<![CDATA[
    var localre = /vlfeat.org/;
    if(document.location.host.search(localre) != -1)
    {
   var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
   document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
   }
   //]]>
  </script>
  <script xml:space="preserve" type="text/javascript">
    //<![CDATA[
    var localre = /vlfeat.org/;
    if(document.location.host.search(localre) != -1)
    {

   try {
   var pageTracker = _gat._getTracker("UA-4936091-2");
   pageTracker._trackPageview();
   } catch(err) {}

   }
   //]]>
  </script>
  <!-- Google Analytics Ends -->
 </body>
</html>

 
